XSB-001 



APPENDIX B 



1 SCOPE 



LI IDENTIFICATION 2 

L2 System Overview 2 
1.3 Document Overview 2 



2 REFERENCED DOCUMENTS 



2.1 Documents Referenced by XSB 3 
3 SOFTWARE SUMMARY 4 

3J Software Application 4 

3.2 Software Inventory 4 

3.3 Software Environment 4 

3.4 Software Organization and Overview of Operation 4 

3.5 Security and Privacy Protection 5 

3.6 Assistance and Problem Reporting 5 



4 ACCESS TO THE SOFTWARE 



4.1 First Time Use of the Software 6 

4.2 Stopping or Suspending work - How to Interrupt Use of the Software and How to 
Determine Whether Normal Termination has Occurred. 6 



5 PROCESSING REFERENCE GUIDE 



5.1 Processing Procedures- 7 

5.2 Related Processing 21 

5.3 Data Backup 21 

5.4 Recovery from Errors, Malfunctions and Emergencies 21 

A -GLOSSARY: 22 



B - THIRD-PARTY SOFTWARE CREDITS 



23 



XSB, Inc Software User Manual 



1 Scope 

1.1 Identification 

This manual is intended for the Restricted Rights release of the XSB, Inc. Generic Matcher 
software to (insert client name here). This release is comprised of the following XSB 
Software elements: 



TITLE 


VERSION 


Generic Matcher 


la 



1 .2 System Overview 

The XSB, Inc. Generic Matcher software was developed to simplify the process of comparing 
two sets of objects based on their common attributes. The User supplies the Matcher with two 
sets of objects contained in a single ontology and then utilize the Matcher to create and edit 
match criteria to power the matching process. 

The Generic Matcher has been under development at XSB, Inc. since July, 2002. XSB, Inc. 
maintains this software at its headquarters located at 25 East Loop Road, Stony Brook NY. 

1 .3 Document Overview 

The purpose of this manual is to assist the user in the installation and responsible operation of 
the Generic Matcher software. This manual is protected by US copyright law and shall not be 
reproduced, duplicated, or distributed beyond (insert client name here) without the express 
written authorization and consent of XSB, Inc. 



2 

This manual is compliant with J-STD-016 Standard for Information Technology Life Cycle Processes 

© 2002 XSB, Inc. 



XSB, Inc Software User Manual 



2 Referenced Documents 

2.1 Documents Referenced by XSB 

The XSB System is open-source in nature and can be freely down-loaded from the website: 
http :// xsb . sourceforpe . net/ . 

The XSB system is a conservative extension of Prolog and includes powerful mechanisms for 
tabling, indexing and non-monotonic reasoning. The XSB system, along with Java are used as 
the major implementation platforms for the Generic Matcher. 
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3 Software Summary 
3.1 Software Application 

XSB's Generic Matcher is a JAVA and XSB based desktop tool that simplifies the process of 
comparing two sets of objects based on their common attributes. Matcher allows the user to 
create, edit match criteria and assign weights to different object attributes to configure the 
matching process. 

Once the attribute matching is complete, Matcher allows users to either store results in the OMS 
format for additional processing or export the results to an MS Access table or a flat delimited 
file. 



3.2 Software Inventory 

REQUIRED SOFTWARE 

1. JRE version 1.4.1 

2. OS; Windows NT/2000/XP 



3.3 Software Environment 

System Memory: Recommended - 256 MB Minimum - 128 MB 

Free Disk Space: Required - Approximately 100MB 

Processor Speed: Recommended - PHI 500 Mhz Minimum - PHI 300 Mhz 

In addition, if you do not a have Java Runtime Environment (JRE) V 1.4.0 or higher installed on 
your computer, you will need run the installer located in the "JRE" directory, which will be 
located on the software CD. Follow the instructions and prompts provided by the installation 
software. 

Be sure to restart your computer after the installation has completed (the installer should 
prompt you to restart when finished). 



3.4 Software Organization and Overview of Operation 
The ODE Constructor Software provides: 

- A graphical user interface to edit, create match criteria and invoke the matching process on 
two sets of objects. 

- A color coded scheme to show in detail the results of the matching process. 

- Pre-Defined matching functions that provide specialized comparison facilities for different data 
types. 

- An import objects feature allowing users to import objects from a flat delimited file or MS 
Access table into the ontology. 



Performanc e Characteristics: 
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- The Generic Matcher application currently accepts the following types of input: 
Manual text inputs, Text files, MS Access files. 

- Currently, Matcher writes output results to OMS files by default; however, the user has the 
ability to save match results in a flat delimited file or MS Access table. 

- Typical program response time varies and is determined by a number of factors including the 
number of objects being compared, the size of the ontology being used, the efficiency of the 
matching functions and the limitations of the processor and ram of the user's computer. 

3.5 Security and Privacy Protection 

The XSB Generic Matcher software application and the related software documentation are 
distributed as Restricted Rights Software to (insert client name here). Both the software 
code and the related software documentation are protected by US copyright law and may not 
be reproduced or distributed, in whole or in part, without the express written permission and 
authorization of XSB, Inc. 

3.6 Assistance and Problem Reporting 

Technical support is available through: 

XSB, Inc., 

25 East Loop Road 
Stony Brook, NY 11790 

Voice: (631) 444-6800 

Fax: (631)444-6775 
Email: support@xsb.com 
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4 Access to the Software 

4.1 First Time Use of the Software 

There is a batch file called "generic_matcher.bat" requiring 128MB of memory that runs the 
Generic Matcher application; to start and run the application, double-click the file referenced 
above. 

Generic Matcher does offer users the ability to modify application settings and preferences but 
none of them have to be configured by the User at the start of the application. 



4.2 Stopping or Suspending work - How to Interrupt Use of the 
Software and How to Determine Whether Normal Termination 
has Occurred. 

A Generic Matcher session and its state can be saved to disk using the Save OMS item from the 
File menu pull down list; it can also be resumed at a later time by loading it back into the 
system using the Load OMS File menu item and providing the name of the directory where the 
OMS was previously saved. 

It is recommended that, while working with the Generic Matcher, you periodically save the 
current OMS (which contains the state of the Matcher), in order to preserve your work. Since 
the software is still in alpha form, software bugs may cause the system to crash. If you have 
saved your work, after a crash you can restart from that point by re-executing the Generic 
Matcher and opening up the most recently saved version of the OMS. 

It is also recommended that you periodically use "Save OMS As ..." to save a copy of the OMS in 
a new directory. Again this will allow you to restore your work to the point of saving. This is 
important to guard against software bugs that might corrupt the OMS, and against user errors 
that are not reversible or are not discovered until after an OMS has been saved. 

*Note: The Generic Matcher will prompt you with an exit warning screen each time you 
attempt to close the program to remind you to Save the OMS. 
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5 Processing Reference Guide 
5.1 Processing Procedures - 



Loading an existing Ontology - 

To load an existing ontology select the Load OMS option from the File menu. You will then be 
prompted to select the directory where OMS is located; once you have selected the OMS, click 
the OK button to load the file into the Generic Matcher application. 



This command removes any previously loaded OMS 
and loads in the new OMS. If you do not want to 
unload the previous OMS you can use the Merge 
OMS command. Other options available in this menu 
allow you to save the OMS. By saving the OMS you 
are also saving any match criteria you may have 
added or modified. The Save OMS Schema command 
lets you save the only the schema part of the OMS, 
this includes concepts, relationships and match 
criteria objects. 



I|3 Matcher v0.99alpha - C:\xsbsys\XSBCVS\a 


|RJg3 Windows Help Matcher 


S Load OMS... 
ft Merge OMS... 






® Save OMS 

© Save OMS As... 

0 Save OMS Schema... 


Jave ft Unloai 




s{0} 
iin f0> 


1 Unload OMS.. 


Exit 



Fig. 1 



Working with the Display Windows - 



The main Generic Matcher display window is divided on two parts - the left panel, and the right 
panel. The left panel displays the currently loaded ontology; the right panel is used to create 
and edit match criteria. 
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Figure 2 below illustrates both the left and right panels. The right panel contains information 
about the attributes of the source and target classes while the left panel indicates what the 
source and target classes are and where they lie in the ontology. 
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Fig 2 

The left panel is split horizontally into two separate components each displaying the currently 
loaded ontology. The user begins the matching process by first selecting the source and target 
classes. The source class is chosen from the top tree and the target class is in the bottom tree 
(see Figure 3). The number next to the name of the class is the number of objects that are 
members of this class. The User can also view the relationships associated with this class by 
right clicking on the node and choosing the View Relationships option. Another option that is 
available when you right click on a node is the ability to import objects from a delimited flat file 
or database table. The User also has the ability to add new classes and relationship under this 
node. Once you have chosen both the target and source attribute the right panel of the main 
window will be rendered. At this point the matcher will try to find a stored default match criteria 
for these two classes. If it is found its settings will be displayed, otherwise the matcher will 
create a new default match criteria. This process can take some considerable time depending 
on the number of attributes under the source and target class and the limitations of the 
processor and ram. 
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Fig 3 



Managing match criterion - 



The right panel is composed of three different components allowing the user to create, delete, 
and modify match criteria. 

1. The top component allows the User to choose from the different match criteria associated 
with this pair of source and target classes. All pairs of source and target classes have a 
default match criteria associated with them. The default criteria can be modified but cannot 
be deleted. 

a. Add Button: Creates a copy of the current match criterion and adds it to the drop 
down box. Once the button is clicked the matcher will prompt the User to name the 
new criteria. Once the match criterion has been named it will be set as the selected 
criteria in the drop down box. When a new match criterion is created the settings of 
the previous criterion are copied into the new one. 

b. Remove Button: Deletes the currently selected match criterion in the drop down box. 
Note: The User does not have the ability to delete the default match criterion. 
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c. Drop down Box: Displays the currently selected match criteria. The settings 
associated with this match criteria are displayed in the middle component of the 
right panel. To change the match criteria just select it from the drop down box. 
2. The middle component of the right panel contains the settings associated with the currently 
selected match criterion are displayed. There are four columns: Source relationship, Target 
Relationship, Matching Function and Weight. 

a. Source Relationship: Relationship associated with the source class 

b. Target Relationship: Relationships from the target class are of the same type as 
the source relationship. The User can choose from any one of the different 
choices available in the drop down box. To prevent the Matcher from comparing 
values of this attribute choose the null value in the drop down box. 

c. Matching Function: Matching functions are specialized prolog predicates used by 
the matcher to compare values of a specific data type. The Generic Matcher has 
various built-in matching functions. The User can select from the different 
matching function available depending on the data type of the values being 
compared. The default matching function is the Equals matching function; it 
applies to all data types. It is the User's responsibility to choose the best and 
most efficient matching function for each attribute being compared. All matching 
functions return a score between the values of [-1.0, + 1.0]. 

d. Weight: Weights provide a way to give precedence to a particular attribute over 
others in the matching process. There is no set limit to what the User can set the 
weight to. An attribute with a weight of 0.0 is not compared. 

e. Highest Possible Score: This is an aggregate of all the weights of all attributes 
being compared. To update this value the User must click on the Update Total 
button (see Fig 4). 

3. The bottom component contains the score cutoff and the match button 

a. Score Cutoff: The score cutoff value determines what match results are returned. 
Match results which have a score greater than or equal to the score cutoff will be 
returned. Note : the score cutoff value should not be higher than the highest 
possible score. 

b. Select Objects to Match: Once the match criterion has been set the User can 
start the match process by pressing this button. When the button is pressed a 
window displaying all objects under the source class will be displayed. 
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Fig 4 



Selecting objects to match- 



The object chooser window displays all the objects under the source class. The name and 
native id of these objects are displayed. The User can choose any number of objects to 
compare or can select all the objects are under the class. To select multiple objects use the Ctrl 
and shift keys to select contiguous and noncontiguous objects. To match only the selected 
objects click on the Match Selected Objects button or to match all objects click on the Match All 
Objects button. 
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Fig 5 



Match Results - 

The match results windows shows all the matches above the cutoff. Four different columns are 
displayed in this window: 

• Native Id of the source object. 

• The score of the best match. 

• The number of target objects that matched. 

• The number of target objects that attained the best score. 

To save the results to a bar delimited flat file click on the Save to File button located at the 
bottom of the match results window. Matcher will prompt you specify the location where the 
results are to be saved. If the User chooses an existing file the he/she will be prompted before 
Matcher overwrites the contents of the file. To save the match results to an MS Access 
database table click on the Save to Db button located at the bottom of the window. Matcher will 
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prompt the User to specify the location of the Access Database and the name of the database 
table where the results are to be saved. If the table exists and its structure is compatible with 
that needed to save the results it will be appended, otherwise the user will be prompted to 
choose another table. If the table does not exist it will be created. 



The User can also choose to view in detail what target attributes matched and see in graphical 
form the reasoning behind the score for a particular source object. To bring up the detail view, 
right click on the source object of interest and choose the View All Matching Target Objects 
option. 
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Detail Results window- 



Fig 6 



Like the right panel in the main window the detail results window is also composed of the three 
distinct components. 

1. The top part of the window is used to display information about the source object. The 
name of the attributes, their values and the weights associated with each are displayed. 
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The highest possible score that can be achieved taking into account the weights is 
shown in the last line; in this case it is equal to 9.0. 

2. The main part of the window displays the target objects that matched the source object, 
the total score of the match along with the values of attributes associated with the 
target objects. A color coding scheme is used to distinguish between values that were 
compared and matched, were compared and didn't match, and those that were not 
compared. 

• In this particular example the color green is associated with values that were 
compared and matched. In the example the first target object has the same 
length as the source object, 18.0 inches. The second value in this cell 
[1.0000] is the score associated with this match. This is equal to the value 
returned by the matching function (matching functions always return a value 
between -1.0 and 1.0) multiplied by the weight entered for the source 
relationship. 

• The color red is associated with values that were compared but did not 
match. Again looking at the first row the source and target object values for 
the "Size Designator" attribute don't match. 

• If the target object has a populated value for an attribute but the source 
object does not, no comparison occurs, e.g. "Needle Design Designation" 
attribute in the first row. The cell for this attribute is colored gray and the 
value of the target attribute is displayed with no score. If the reverse 
happens and the source object has a value and the target object does not as 
is the case for "Material and Location" attribute, the corresponding cell is left 
empty and colored gray. 

• It is often the case that for an attribute a target object may have multiple 
values. When this occurs a second row for the object is inserted into the 
table and the whole row is colored white. The second row in figure 7 is an 
example of this. One of these values is matched to by the matcher and the 
appropriate coloring is used. In this case the second value for the "Needle 
Type Designator" attribute is compared and a score of [-1.0000] is assigned. 

3. The colors used for these different situations can be changed at any time by using the 
drop down boxes in section 3 of the window. They can also be changed using the Set Colors 
menu item located in the Matcher menu in the main window. 
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Fig 7 



Adding a new class to the OMS - 

The generic matcher provides some rudimentary OMS editing functions. One of these is the 
ability to add a new class to the OMS. To add a class, select the node, under which you want 
the new class to appear, right click and choose the "Modify OMS/Add a new Class" option from 
the pop up menu. Generic Matcher will prompt the User to enter the name, native id and source 
of the new class. The User has the option to make the new class a parameterized class. This is 
done by checking the box next to the "Parameterized Class" label and entering the arity of the 
class below it. If the new class is a parameterized class the use will be prompted to choose 
from the existing concepts in the OMS the arguments of the class. 

If the class was added successfully it will appear under the parent node when you click 

ok. 
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Fig 8 



Adding a new relationship - 



Along with the ability to add a new class to the OMS, the Matcher provides the ability to add 
relationships to the class. To start this process select the class you want to modify, right click on 
the node and select the "Modify OMS/Add a new Relationship" option. The User will be 
prompted to the name of the new relationship. The User must also specify the type of the 
relationship, i.e. what type of values will this relationship have e.g. string, number, measure etc. 
To verify whether the new relationship was added properly you can always view the 
relationships attached to a class by right clicking on the node and selecting the View 
Relationship option. 




IX 



Relationship Name: 
Relationship Type : 



String 



OK 




Cancel 







Fig 9 

Importing objects into the OMS - 

The Generic Matcher provides the ability to import objects from either a delimited file or MS 
Access table. To start the process right click on the node under which you want to the objects 
inserted. Select the Import Objects from File/Db option; Matcher will prompt you to select the 
batch file or Access database file. Navigate through the directory structure and click on the 
"Import" button to load the file into the Matcher. 
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To load files from a Access select the database file (*.mdb), 
Matcher will prompt the User to enter the name of the database 
table from which to import the objects. Otherwise the User will be 
prompted to select a column delimiter for the batch text file to be 
loaded into the Matcher. The User will have the option of 
choosing from pipe, comma, colon, and tab as possible file 
delimiters (see Figure 10). Once the appropriate delimiter has been 
selected, the User should press the Ok button to prompt the 
Matcher to load the batch file. 



Edit 



i Please choose field delimiter 



j® (I) 

c 

i O Comma (,) 

r 

jQ Colon (:) 
lOTab 



OK 



Cancel 



An editor will now be displayed, allowing the User to select which 
columns of the batch file or fields from the database table they 
want imported. Under the First Line/Title heading, the User will Fig 10 

see a list of all of the names or titles of the columns in the text file 

(It is assumed that first row of the file contains column names separated by a pre-selected file 
delimiter). The User will now need to select appropriate designations for each of these columns 
from the drop down list found under the Relationships heading. The Relationship designations 
for each column are essentially a set of instructions on how the Matcher should handle the 
information contained within the column. To select a Relationship designation for an attribute, 
the User must triple click on the drop down box in the Relationships column and select one of 
the options displayed. 




OK Cancel 



Fig 11 
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Editing User preferences - 

Matcher provides a central location where preferences can be managed. To edit preferences 
select the Edit Preferences menu item under the Matcher menu. A dialog box will appear listing 
the various options that can be set. Once you have set all the options simply close the dialog box. 
All the User specified preferences are saved in the prefs file located in the application directory; 
it is recommended that the User not edit this file. 

• OMS Load Dir: This is the directory to which Matcher opens the file dialog when the 
User uses the Load OMS or Merge OMS options. 

• OMS Startup Dir: The User can specify for an OMS to be loaded by default each time the 
matcher starts up. 

• Previous Match Results: Whenever a match is executed in the generic matcher 
information regarding scores is added to the OMS as an attribute of the source object. If 
you wish not to save this information choose this option. It is important to note that this 
option causes adverse effects if any result windows are open when saving occurs. 

• Scoring Information: By default when matcher saves match results the individual scores 
assigned to object attributes are not saved. If the user chooses this option the scoring 
information will be saved along with the attribute values. 

• Maximize @Startup: Option to maximize the window at startup. 

• Hide System Nodes: Option to hide class nodes in the source and target trees for concepts 
that have a system source, e.g. OMS, TMS, ODE, ODC etc. . 

Another selection available under the "Matcher" menu is the option to "Write Results directly to 
file." When this option is selected the results window will not appear when a match is completed 
instead the user will be asked whether he/she wants to save the results to a file or a database. 



Edit Preferences 






Edit 


OMS Load Dir: 


CVS/apps/weave/oms_matcher/matcher_gui 




Browse... 




OMS Startup Dir: 




□ ON*)FF 




J Remove previous match results before saving (Experimental) 






J Save Score Information when savingto File/Db 








J Maximize ^Startup 








J Hide System Nodes 









Fig 12 

Help Browser- 
Generic matcher provides built in help features including the help browser. The help browser 
allows the user to view application documentation and view answers to frequently asked 
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questions. To invoke the help browser simply click on the Help Contents menu item under the 
Help menu. The help browser is very similar to an internet browser and provides quick answers 
to questions. 



Manual 




Edit 




< LvxJ; > Hji A' an! © Home; Address 


file://C:&st3sys/X^ 


Introduction 




The main purpose of the generic matcher tool is to allow for the comparison of two different sets of objects 
based on their common attributes. For this purpose the generic matcher provides a user friendly gui, presenting 
the user with total control over how and what is matched. The objects are compared on the basis of attributes of 
the source object. It is helpful to go over some terms used when talking about generic matcher. The 
class/concept containing objects that are being compared is referred to as the source class, whereas the class 
containing the objects ageinst which the source objects are being compared is referred to as the target class. The 
source and target class must be part of the same ontology. Match criteria is a set of tuples for each source 
attribute being compared. A tuple in this case contains the source attribute, the target attribute it is being 
compared to (can be null), the matching function being used to facilitate the comparison and the weight 
associated with this attribute. 


Contents 

♦ Starting uo the matcher 

♦ Loading an ontoloev 

\ * Choosing source/target classes 

♦ Managing match criteria 

♦ Selecting objects to match 

♦ Match results 

♦ Detail results window 

♦ Saving results 




Home Back Next 





Fig 13 



Matching function descriptions 

To view a description about the available matching functions, along with how they handle 
scoring click on the Function Descriptions menu item under the Help menu. This feature 
provides information about every matching function that is currently bundled with the Matcher 
and have been loaded. 
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Matching Function Description 



Edit 



Function : 



Phone Number Matching Function 



Description : 

Allows the matching of phone numbers represented 
in atomic form. Phone numbers being matched can 
be either 7 or 1 0 digit numbers. The values passed 
to this matching function should contain only the 
numbers e.g. Num1=555 4545 Num2=(333)-444-5555. 



Scoring : 
Component Match/Mismatch 
Area Code +0.4Q/-0.50 
Extension +0.40/-0.50 
Number +0.20/-0.00 



Fig 14 
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5.2 Related Processing 

When the User selects a pair of source and target classes in a session, the Matcher will run 
background processing in order to generate or load default match criteria; this may cause a 
delay for the User as they will have to wait several seconds for the background processing to be 
completed. 



5.3 Data Backup 

Normal database management backup procedures should be used in conjunction with the 
Generic Matcher software; users should be careful to back up the OMS directory used for saving 
the intermediate state of the Generic Matcher as well as input and output data as part of their 
routine backup procedure. 

5.4 Recovery from Errors, Malfunctions and Emergencies 

Should your software malfunction or should you encounter an error that prevents you from 
continuing to use the software as prescribed in this manual, contact technical support 
immediately at 631-444-6800 or via email at support@xsb.com . 
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A - Glossary: 

Class - (sometimes referred to as a node or a concept) a set containing members regarded as 
having certain relationships in common, a kind or category. 

Match Criterion - the source and target class, the set of attributes being compared, the 
weights and matching function associated with each attribute and the score cutoff all together 
form the match criterion. 

Matching Function - specialized prolog predicate used by the matcher to compare two values 
of a particular data type. Matching functions always return a value between [-1.0,+1.0]. 

OMS - ontology management system to manage and store ontology-based knowledge. 

Parameterized Class - represents an infinite set of Values such as integers, measures and so 
on. For example, number of Stents in a package may be any integer - we can not name all of the 
possible Values. 

Source Class - the class in the ontology containing the set of objects that are currently being 
compared. 

Target Class - the class in the ontology containing the set of objects that the source objects 
are being compared against. 

Source Object - a member of the source class. 

Target Object - a member of the target class. 
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B - Third-party Software Credits 



The Generic Matcher makes use of several third-party software packages. Some of these are 
recognized below. 

• This product includes code licensed JRE v 1.4 by SUN Microsystems 

• This product makes use of the open source XSB code 

• This product makes use of the Java Look and Feel Repository 



The developers of these third-party software programs do not warrant their software in any 
way. See the dist and lib directories for more information about these software programs and 
their licenses. 
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